The section describes the programming interface of the RTC Peripheral Driver. More...

Data Structures
struct	rtc_datetime_t
	Structure is used to hold the time in a simple "date" format. More...

struct	rtc_time_t
	Time representation: hours, minutes, second and total seconds. More...

struct	rtc_user_config_t
	RTC timer configuration structure. More...

Macros
#define	FSL_FEATURE_RTC_INTERRUPT_COUNT (2)

Typedefs
typedef void(*	rtc_isr_callback_t )(void)
	RTC ISR callback function typedef.

Initialize and Shutdown
bool	rtc_init (const rtc_user_config_t *config)
	Initializes the Real Time Clock module. More...

void	rtc_shutdown (void)
	disable RTC module clock gate control. More...

RTC interrupt configuration and status
void	rtc_configure_int (hw_rtc_ier_t *bitfields)
	Enables/disables RTC interrupts. More...

void	rtc_get_int_status (hw_rtc_sr_t *int_status_flags)
	Returns the RTC interrupt status flags. More...

RTC datetime set and get
bool	rtc_set_datetime (const rtc_datetime_t *datetime, bool start_after_set)
	Sets the RTC date and time according to the given time structure, if indicated in the corresponding parameter. More...

void	rtc_get_datetime (rtc_datetime_t *datetime)
	Gets the actual RTC time and stores it in the given time structure. More...

RTC alarm set and get
bool	rtc_set_alarm (const rtc_datetime_t *date)
	Sets the RTC alarm. More...

bool	rtc_get_alarm (rtc_datetime_t *date)
	Returns the RTC alarm time. More...

RTC time counter start and stop
void	rtc_start_time_counter (void)
	Enables the RTC oscillator and starts time counter. More...

void	rtc_stop_time_counter (void)
	Halts running time counter. More...

Copy time data
void	rtc_cp_datetime_time (const rtc_datetime_t datetime, rtc_time_t time)
	Utility to copy time data from datetime structure to a time structure. More...

void	rtc_cp_time_datetime (const rtc_time_t time, rtc_datetime_t datetime)
	Utility to copy time data from time structure to a datetime. More...

ISR Callback Function
void	rtc_register_isr_callback_function (uint8_t rtc_irq_number, rtc_isr_callback_t function)
	Register RTC ISR callback function. More...

RTC Peripheral Driver

Overview

The RTC peripheral driver is used to set and get the RTC clock, set and read the RTC alarm time and receive notifications when an alarm is triggered.

User configuration structures

The RTC driver uses an instantiation of the rtc_user_config_t structure to configure the RTC driver. This allows the user to configure the most common settings of the RTC driver. The rtc_user_config_t structure holds an instance of the rtc_hal_init_config_t (see RTC HAL Driver for details) and rtc_datetime_t data-types. The rtc_hal_init_config_t holds information used by the RTC HAL driver & rtc_datetime_t, which allows the user to pass in the date and time information stored in the RTC seconds register.

Initialization

To initialize, the user calls rtc_init() with a pointer to the rtc_user_config_t structure. The driver initialization function ungates the RTC module clock. It then uses the information passed in to initialize the RTC HAL layer driver (this part is skipped if the "general_config" element is set to NULL) and the RTC time (this part is skipped if the "start_at_datetime" element is set to NULL).This is an example code to set up a user RTC configuration instantiation:

rtc_user_config_t rtc_drv_configs = {
    .general_config = &rtc_init_configs,
    .start_at_datetime = NULL,
};    

This is an example to make the rtc_init() function.

/* init the rtc module */

rtc_init(&rtc_drv_configs);

Setting and reading the RTC time

The RTC driver uses an instantiation of the rtc_datetime_t structure to configure or read the date & time.This is an example code to set up a user RTC configuration instantiation:

rtc_datetime_t datetimeToSet;
datetimeToSet.year = 2013;
datetimeToSet.month = 10;
datetimeToSet.day = 13;
datetimeToSet.hour = 18;
datetimeToSet.minute = 55;
datetimeToSet.second = 30;  

The user can pass the date and time as part of the rtc_user_config_t structure during driver initialization or can call the rtc_set_datetime() or rtc_get_datetime() functions to configure or read the date & time at a later time. This is example to use these functions.

/* get datetime  */
rtc_get_datetime(&datetime);
printf("Current datetime: %04hd-%02hd-%02hd %02hd:%02hd:%02hd\r\n",
          datetime.year, datetime.month, datetime.day,
          datetime.hour, datetime.minute, datetime.second);
/* set the datetime */
result = rtc_set_datetime(&datetime, true);

Triggering an Alarm

The RTC driver uses interrupts when an alarm is triggered at a user-specified time. The user has to register a callback function that is invoked when the alarm interrupt is triggered.The user can call the rtc_set_alarm() to set the alarm time or the rtc_get_alarm() to read the configured alarm time. The user has to set the current time using the steps mentioned earlier prior to using the call to set the alarm time. This is an example of how to use these functions.

rtc_datetime_t datetimeToSet;
rtc_set_datetime(&datetimeToSet, false);
datetimeToSet.second += 5;
rtc_set_alarm(&datetimeToSet);
/*Register a callback function.*/
rtc_register_isr_callback_function(0, alarmISR);
/* Enable the Alarm interrupt */
rtc_hal_config_alarm_int_enable(true);

Data Structure Documentation

struct rtc_datetime_t

Warning: If you violate the ranges, undefined behavior results.

Data Fields
uint16_t	year
	Range from 200 to 2099. More...

uint16_t	month
	Range from 1 to 12. More...

uint16_t	day
	Range from 1 to 31 (depending on month). More...

uint16_t	hour
	Range from 0 to 23. More...

uint16_t	minute
	Range from 0 to 59. More...

uint8_t	second
	Range from 0 to 59. More...

Field Documentation

uint16_t rtc_datetime_t::year

uint16_t rtc_datetime_t::month

uint16_t rtc_datetime_t::day

uint16_t rtc_datetime_t::hour

uint16_t rtc_datetime_t::minute

uint8_t rtc_datetime_t::second

struct rtc_time_t

Data Fields
uint16_t	hour
	Range from 0 to 23. More...

uint16_t	minute
	Range from 0 to 59. More...

uint8_t	second
	Range from 0 to 59. More...

Field Documentation

uint16_t rtc_time_t::hour

uint16_t rtc_time_t::minute

uint8_t rtc_time_t::second

struct rtc_user_config_t

Data Fields
rtc_hal_init_config_t *	general_config
	Pointer to a structure most of the configurations.

rtc_datetime_t *	start_at_datetime
	are found. More...

bool	start_counter
	Set to true to start the real time counter. More...

Field Documentation

rtc_datetime_t* rtc_user_config_t::start_at_datetime

Set to NULL to skip related configuration.

See the 'rtc_hal_init_config' definition for details. Initial datetime. Set to NULL to skip.

bool rtc_user_config_t::start_counter

Will

Function Documentation

bool rtc_init ( const rtc_user_config_t * config )

Parameters

Config [in] initialization configuration details.

Returns: True: success; false: datetime format is invalid or the counter indicated to start but it was already started.

void rtc_shutdown ( void )

void rtc_configure_int ( hw_rtc_ier_t * bitfields )

Parameters

bitfields [in] set/clear respective bitfields to enabled/disabled interrupts.
[out] resulting interrupt enable state.
Valid bitfields:
TSIE: Time Seconds Interrupt Enable
TAIE: Time Alarm Interrupt Enable
TOIE: Time Overflow Interrupt Enable
TIIE: Time Invalid Interrupt Enable

For MCUs that have the Wakeup Pin only:
WPON: Wakeup Pin On (see the corresponding MCU's reference manual)

For MCUs that have the Monotonic Counter only:
MOIE: Monotonic Overflow Interrupt Enable

void rtc_get_int_status ( hw_rtc_sr_t * int_status_flags )

Parameters

int_status_flags [out] pointer to where to store bitfield with an actual RTC interrupt flags.
ONLY valid bitfields:
TIF: Time Invalid Flag
TOF: Time Overflow Flag
TAF: Time Alarm Flag
MOF: Monotonic Overflow Flag (Not in all devices)
Note: other bitfields are not to be taken in account.

bool rtc_set_datetime	(	const rtc_datetime_t *	datetime,
		bool	start_after_set
	)

After, the time counter is started.

Parameters

datetime	[in] pointer to a structure where the date and time details are stored.
start_after_set	true: the RTC oscillator will be enabled and the counter will start. False: otherwise.

Returns: True: success; false: error, datetime format incorrect, datetime format is invalid or unable to set the counter value because it is already enabled.

void rtc_get_datetime ( rtc_datetime_t * datetime )

Parameters

datetime [out] pointer to structure where the date and time details will be stored.

bool rtc_set_alarm ( const rtc_datetime_t * date )

Parameters

date	[in] pointer to structure where the alarm date and time details will be stored.

Returns: true: success; false: error.

bool rtc_get_alarm ( rtc_datetime_t * date )

Parameters

date	[out] pointer to structure where the alarm date and time details will be stored.

Returns: True: success; false: error.

void rtc_start_time_counter ( void )

void rtc_stop_time_counter ( void )

void rtc_cp_datetime_time	(	const rtc_datetime_t *	datetime,
		rtc_time_t *	time
	)

Parameters

datetime	[in] data origin
time	[out] data destination

void rtc_cp_time_datetime	(	const rtc_time_t *	time,
		rtc_datetime_t *	datetime
	)

        structure.

Parameters

time	[in] data origin
datetime	[out] data destination

void rtc_register_isr_callback_function	(	uint8_t	rtc_irq_number,
		rtc_isr_callback_t	function
	)

System default ISR interfaces are already defined in the fsl_rtc_irq.c. Users can either edit these ISRs or use this function to register a callback function. The default ISR runs the callback function if one is installed.

Parameters

rtc_irq_number	RTC interrupt number.
function	Pointer to the RTC ISR callback function.

Data Structures

Macros

Typedefs

Initialize and Shutdown

RTC interrupt configuration and status

RTC datetime set and get

RTC alarm set and get

RTC time counter start and stop

Copy time data

ISR Callback Function

RTC Peripheral Driver

Overview

User configuration structures

Initialization

Setting and reading the RTC time

Triggering an Alarm

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Function Documentation